#region (c) 2014 THN Solutions LLC. - All rights reserved
/*
THN DATA ABSTRACTION LAYER version 1

Copyright (c) 2014, THN Solutions LLC. ( www.ThnSolutions.com )
Author: Nguyễn, M. Hải                 ( www.Minh-Hai.com     )
All rights reserved.

This library is dual-licensed.
  + For commercial software, please obtain a commercial license from THN Solutions LLC.

  + For free software, this library is licensed under GPL version 3. A summary of GPLv3 is
    listed below. You should also find a copy of GPLv3 as file License_GPLv3.txt included
	with the source-code files.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License version 3 as published by
    the Free Software Foundation  of the License.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/
#endregion

#region Using directives
using System;
using System.Collections;
using Thn.Data.Query;
#endregion

namespace Thn.Data.Persistence
{
    /// <summary>
    /// A persistent context is a single-thread, single-user persistence service.
    /// <para>This context provides object caching, command logging, as well as relationship handling.</para>
    /// </summary>
    public interface IPersistentContext
    {
        #region Cache
        /// <summary>
        /// Gets/Sets the cache this context uses for storing objects
        /// </summary>
        IPersistentCache Cache
        { get;set;}
        #endregion

        #region Add
        /// <summary>
        /// Insert new object
        /// </summary>
        void Add(IPersistentObject value);

        /// <summary>
        /// Insert an array of objects
        /// </summary>
        void Add(params IPersistentObject[] values);

        /// <summary>
        /// Insert a list of objects
        /// </summary>
        void Add(IList values);
        #endregion

        #region Update
        /// <summary>
        /// Update an object
        /// </summary>
        void Update(IPersistentObject value);

        /// <summary>
        /// Update an array of objects
        /// </summary>
        void Update(params IPersistentObject[] values);

        /// <summary>
        /// Update a list of objects
        /// </summary>
        void Update(IList values);
        #endregion

        #region Delete
        /// <summary>
        /// Delete an object
        /// </summary>
        void Delete(IPersistentObject value);

        /// <summary>
        /// Delete an array of objects
        /// </summary>
        void Delete(params IPersistentObject[] values);

        /// <summary>
        /// Delete a list of objects
        /// </summary>
        void Delete(IList values);
        #endregion

        #region Select
        /// <summary>
        /// Gets a new select query
        /// </summary>
        SelectQuery Select
        { get;}
        #endregion

        #region Parent
        /// <summary>
        /// Gets the persistent layer that this context belongs to
        /// </summary>
        IPersistentLayer Parent
        { get;}
        #endregion

        #region Transaction
        /// <summary>
        /// Start a new transaction scope.
        /// <para>The new scope will be nested within the current scope (if available)</para>
        /// </summary>
        /// <returns>ID of the new transaction scope</returns>
        object Begin();

        /// <summary>
        /// Accept and close a transaction scope
        /// </summary>
        /// <param name="scopeID">ID of the transaction scope</param>
        void End(object scopeID);

        /// <summary>
        /// Discard modifications made within a transaction scope
        /// </summary>
        /// <param name="scopeID">ID of the transaction scope</param>
        void Cancel(object scopeID);
        #endregion

        #region Undo / Redo
        //#region Undo
        ///// <summary>
        ///// Discard the previous command
        ///// </summary>
        //void Undo();
        //#endregion

        //#region Redo
        ///// <summary>
        ///// Re-apply the previously undone command
        ///// </summary>
        //void Redo();
        //#endregion
        #endregion

        #region Persist
        /// <summary>
        /// Save changes to physical database
        /// </summary>
        void Persist();
        #endregion

        #region Find
        /// <summary>
        /// Find a certain object based on its identifier
        /// </summary>
        /// <param name="objectType">type of the persistent object</param>
        /// <param name="id">identifier of the object to find</param>
        /// <returns>null if no matching object found</returns>
        IPersistentObject Find(Type objectType, object id);
        #endregion        

        #region Modified
        /// <summary>
        /// Gets whether there are modifications need to be persisted
        /// </summary>
        bool Modified
        { get;}
        #endregion

        #region Events
        /// <summary>
        /// Raised when there is new activity occured
        /// </summary>
        event EventHandler Changed;
        #endregion
    }
}
